package nevo.core;

import java.util.*;

/**
 * This class is is passed a map of name-value pairs and expected to
 * produce an output in the form of a Map&lt;String,Object&gt; containing
 * the names and values of output variables that a given implementation
 * of {@link ObjectiveFunction} can understand. <i>Models are meant
 * to be stateless - they shouldn't modify member variables from their
 * {@link #run(ModelInput)} method.</i>   
 * 
 * @author mschachter
 */
public interface Model
{		
	/**
	 * Take a given input and produce an output.
	 * @param m An instance of {@link ModelInput} that contains a list of
	 * 		  names and values. For flexibility, at the cost of a little
	 * 		  confusion, the value of an input is unconstrained. Its the
	 * 		  responsibility of the function implementation to respond
	 * 		  appropriately when given a malformed {@link ModelInput}.
	 * @return A Map of names and values representing the variables that are output
	 * 		  from this model, given the input. The output is then passed to
	 *         an implementation of {@link ObjectiveFunction}. Its the responsibility
	 *         of the objective function to throw exceptions when given a malformed
	 *         Map<String,Object> to compute with.
	 * @throws Exception If something goes wrong, throw an exception.
	 */
	public Map<String, Object> run(Map<String, Object> m) throws Exception;
	
	/**
	 * Whether or not multiple calls to this model can be efficiently run in
	 * parallel.
	 */
	public boolean isParallel();
}
